Inside Macintosh: QuickDraw GX Programmer's Overview / Part 2 - The QuickDraw GX Programming Cookbook

Chapter 4 - Using the QuickDraw GX Environment

Initializing QuickDraw GX

This programming recipe discusses how you can initialize the QuickDraw GX environment and allocate QuickDraw GX memory for your application.

You should be sure your application initializes QuickDraw GX properly, as described in this recipe, before you use code from any of the recipes that appear later in this book.

Overview of Recipe Steps

The steps in this recipe show you how to:

1. Determine whether QuickDraw GX is available
2. Determine whether the debugging version is available
3. Respond if QuickDraw GX is not available
4. Create a new graphics client
5. Allocate and initialize the graphics client heap
6. Initialize QuickDraw GX printing

Some of the steps in this recipe are optional. For example, after you have completed debugging your application, you will no longer have to include
the code from Step 2 to determine if the debugging version of QuickDraw GX is available. However, while you are developing your application, you will probably want to include the sample code from all of these recipe steps.

Functions Used in This Recipe

QuickDraw GX functions used in this recipe:

GXNewGraphicsClient	"QuickDraw GX Memory Management" QuickDraw GX Environment and Utilities
GXEnterGraphics	"QuickDraw GX Memory Management" QuickDraw GX Environment and Utilities
GXInitPrinting	"Core Printing Features" QuickDraw GX Printing
GXGetGraphicsError	"Errors, Warnings, and Notices" QuickDraw GX Environment and Utilities

Standard Macintosh functions used in this recipe:

Gestalt	"Gestalt Manager" Operating System Utilities
SysEnvirons	"Gestalt Manager" Operating System Utilities
GetIndString	"Text Utilities" Text
ParamText	"Dialog Manager" Macintosh Toolbox Essentials
StopAlert	"Dialog Manager" Macintosh Toolbox Essentials
ExitToShell	"Process Manager" Processes

This recipe gives a brief description of these functions; you can find complete reference information for these functions in the Inside Macintosh suite of books.

Recipe Step Descriptions

In this section, each step of the recipe is described individually.

1. Determine whether QuickDraw GX is available

   Before you can use any QuickDraw GX functions or even initialize QuickDraw GX, you need to determine whether the QuickDraw GX system software has been installed in the environment in which your application
   is running.

   Boolean MyQuickDrawGXInstalled()
   {
      long version;
    
      if (Gestalt(gestaltGraphicsVersion, &version) == noErr)
        if (Gestalt(gestaltPrintingMgrVersion, &version) == noErr)
          return(true);
   
    return(false);
   }

   This function returns true if QuickDraw GX graphics, typography, and printing are available to your application and returns false otherwise.

   When you pass the gestaltGraphicsVersion selector (a constant defined by QuickDraw GX with a value of 'grfx') to the Gestalt function, it returns two pieces of information:

   • The function result indicates whether the graphics part (including typography) is available. If it is available, the function result is the
     noErr result code.
   • The second parameter points to a long integer that contains the 32-bit version number of the graphics part, if it is available. For example, if version 1.0 of the graphics part of QuickDraw GX is available, the Gestalt function sets the value of this long integer to 0x00010000.

     Similarly, passing the gestaltPrintingMgrVersion selector (a constant defined by QuickDraw GX with a value of 'pmgr') to the Gestalt function determines if the printing part of QuickDraw GX is available, and, if so, which version is available.

     In general, the two parts of QuickDraw GX are both available or neither is available. You shouldn't encounter a situation where one part is available and the other part is not. However, you test for the parts using separate Gestalt selectors because the two parts might have different version numbers.

2. Determine whether the debugging version is available

   You can also use the Gestalt function to determine whether the debugging version of QuickDraw GX is installed:

   long flags;
   
   if (Gestalt(gestaltGraphicsAttr, &flags) == noErr) {
    if (flags & gestaltGraphicsIsDebugging) {
     /* debugging version available */
    } else {
     /* non-debugging version available */
    }
   }

   When you call the Gestalt function with the gestaltGraphicsAttr selector (a constant defined by QuickDraw GX with a value of 'gxfa'), the function returns a set of flags in the long integer pointed to by its second parameter. If the gestaltGraphicsIsDebugging flag (bit 0) is set, the debugging version is installed. If this flag is not set, the non-debugging version is installed.

3. Respond if QuickDraw GX is not available

   Your application should determine whether QuickDraw GX is available before doing any QuickDraw GX initialization or making any calls to QuickDraw GX functions. If the MyQuickDrawGXInstalled function in Step 1 determines that QuickDraw GX is not available (and your application is QuickDraw GX-dependent) you should alert the user that QuickDraw GX is not installed and terminate execution of your application:

   if (!MyQuickDrawGXInstalled()) {
    /* Code to display error message and quit goes here.*/
   }

   You can use standard Macintosh functions to display the error message and terminate your application. For example, you can store the error message string in an 'STR#' resource and use the function GetIndString to retrieve it. Then, you can use the Macintosh functions ParamText and StopAlert to display the error message, and you can use the Macintosh function ExitToShell to terminate your application.

   If your application is QuickDraw GX-aware but not QuickDraw GX-
   dependent, it might be able to execute even if QuickDraw GX is not available. In this case, you would want to set a global variable indicating whether QuickDraw GX was available or not:

   gQuickDrawGXAvailable = MyQuickDrawGXInstalled();

   When your application prints, you can decide whether to use QuickDraw GX functions or standard Printing Manager functions based on the value of the gQuickDrawGXAvailable variable.

   In any case, if QuickDraw GX is available, you can proceed with the initialization process.

4. Create a new graphics client

   Every QuickDraw GX application has two memory heaps:

   • the application heap, which your application manages with the help of the Macintosh Memory Manager
   • the graphics client heap, which QuickDraw GX manages for you

     The graphics client heap is one or more blocks of memory reserved for your application, typically located in the QuickDraw GX heap. This memory is where QuickDraw GX stores the QuickDraw GX objects used by your application.

     QuickDraw GX provides an object type--the graphics client--to encapsulate information about your application's graphics client heap. Before allocating and initializing a graphics client heap, your application should create a graphics client object, using the GXNewGraphicsClient function:

     gxGraphicsClient myGXClient;

     myGXClient = GXNewGraphicsClient(nil,
                                      kMyGXHeapSize * 1024L,
                                      0L);

     The GXNewGraphicsClient function takes three parameters:

   • The first parameter allows you to provide a pointer specifying the initial memory location for the new graphics client heap. If you specify a nil value for this parameter, QuickDraw GX allocates the memory for you outside of your application heap. (You can use this parameter to specify a location in your application heap. However, if you do, QuickDraw GX can never allocate more memory to your graphics client heap.)
   • The second parameter allows you to request a size in bytes for the new graphics client heap. This example uses a constant, kMyGXHeapSize, to store the number of requested kilobytes and multiplies that constant by 1024 to specify the number of bytes. You can also specify a heap size by passing 0 for this parameter and including a 'gasz' resource with your application. (You can use GraphicsBug to help you determine how large to make your graphics client heap by examining the number of free blocks in this heap as your application executes.)
   • The third parameter contains a set of flags that allow you to specify additional information about the graphics client. In version 1.0 of QuickDraw GX, this parameter contains a single flag that indicates whether QuickDraw GX can add additional blocks of memory to the graphics client heap when needed. A value of 0 indicates that it can; a value of 1 (the constant gxStaticHeapClient) indicates that it cannot. (Remember, QuickDraw GX can only allocate more memory for your graphics client heap if it is located in temporary memory.)

     Although the GXNewGraphicsClient function creates a graphics client object, it does not actually allocate or initialize the requested heap. To create a graphics client heap, you can use the GXEnterGraphics function, as described in Step 5. (If you do not explicitly create a graphics client heap, QuickDraw GX creates one for you the first time you call a QuickDraw GX function that requires one.)

     The graphics client object has no accessible properties. Once you create it, you typically do not have to use it again until you exit your application.

     If the GXNewGraphicsClient is unable to create a graphics client object, it returns nil as the function result. After calling this function, you should examine the value of your myGXClient variable; if it is nil, you should display an alert box informing your user that there is not enough memory
     to run your application.

5. Allocate and initialize the graphics client heap

   After creating a graphics client object, you're ready to allocate and initialize your graphics client heap.

Note

You typically initialize error-handling and debugging facilities before you allocate your graphics client heap. See the next recipe, "Setting Up Type Validation and Error Handling," beginning on page 143, for more information.

To allocate and initialize the client graphics heap, you use the GXEnterGraphics function:

GXEnterGraphics();

This function uses the information you specified when creating your graphics client object to allocate and initialize your graphics client heap.
It also initializes some basic data structures used by the graphics and typography part of QuickDraw GX.

Your application does not have to call the GXEnterGraphics function: if you don't call it, QuickDraw GX calls it for you the first time your application calls a QuickDraw GX function that needs to use the graphics client heap.

However, by calling GXEnterGraphics explicitly, you can determine whether QuickDraw GX ran out of memory while trying to allocate your graphics client heap.

If the GXEnterGraphics function is unable to allocate a graphics client heap, it posts an out-of-memory error. You can determine whether this function succeeded by calling the GXGetGraphicsError function:

if (GXGetGraphicsError(nil) == out_of_memory) {
 /* Code to display error message and quit goes here.*/
} 

1. Initialize QuickDraw GX printing

   After your application successfully completes the GXEnterGraphics function, you can initialize the printing part of QuickDraw GX using the GXInitPrinting function:

   OSErr  myQDGXPrintError;

   myQDGXPrintError = GXInitPrinting();

   This function takes no parameters and returns a result code of type OSErr indicating one of the following:

   • The initialization is successful (the result has the value noErr).
   • The initialization fails due to low memory or disk errors (the result has the value segmentLoadFailedErr).

     You can test whether the GXInitPrinting function failed using this code:

     if (myQDGXPrintError) {
      /* Code to display error message and quit goes here */
     }

Important

Although you may call QuickDraw functions after initializing QuickDraw GX, you may not call Printing Manager functions after calling the GXInitPrinting function. In addition to initializing QuickDraw GX printing, you must also create a job object before your application can print anything. See the recipes in Chapter 8, "Printing," for more information about creating job objects and printing with QuickDraw GX.

Once the core parts of QuickDraw GX are initialized, you can initialize any additional parts that your application uses--such as the QuickDraw GX libraries.

Related Recipes

For information related to initializing QuickDraw GX, see these recipes:

• "Setting Up Type Validation and Error Handling," described next, shows how to complete your initialization of QuickDraw GX to include error-
  handling and debugging facilities.
• "Exiting QuickDraw GX," beginning on page 147, shows how to deallocate your graphics client heap and close up your application's connection to the QuickDraw GX world.

The recipes in the next chapter, "Using Macintosh Windows," show you how to connect QuickDraw GX objects to a Macintosh window. You should read the recipes in that chapter before you begin to use QuickDraw GX to draw shapes.

The recipes in Chapter 6, "Handling Graphics," and in Chapter 7, "Handling Typography," show you how to create and manipulate images drawn to
a window.

The recipes in Chapter 8, "Printing," show you how to initialize printing objects, including job objects, and how to send images to a printer.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help